home *** CD-ROM | disk | FTP | other *** search
/ Stone Design / Stone Design.iso / Stone_Friends / Wave / WavesWorld / Source / Libraries / tcl7.4b3 / doc / CrtCommand.3 < prev    next >
Encoding:
Text File  |  1995-02-09  |  7.2 KB  |  187 lines
  1. '\"
  2. '\" Copyright (c) 1989-1993 The Regents of the University of California.
  3. '\" Copyright (c) 1994-1995 Sun Microsystems, Inc.
  4. '\"
  5. '\" See the file "license.terms" for information on usage and redistribution
  6. '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  7. '\" 
  8. '\" @(#) CrtCommand.3 1.14 95/02/09 17:32:59
  9. '\" 
  10. .so man.macros
  11. .HS Tcl_CreateCommand tclc
  12. .BS
  13. .SH NAME
  14. Tcl_CreateCommand, Tcl_DeleteCommand, Tcl_GetCommandInfo, Tcl_SetCommandInfo \- implement new commands in C
  15. .SH SYNOPSIS
  16. .nf
  17. \fB#include <tcl.h>\fR
  18. .sp
  19. .VS
  20. .VE
  21. Tcl_Command
  22. \fBTcl_CreateCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR)
  23. .sp
  24. int
  25. \fBTcl_DeleteCommand\fR(\fIinterp, cmdName\fR)
  26. .sp
  27. .VS
  28. int
  29. \fBTcl_GetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)
  30. .sp
  31. int
  32. \fBTcl_SetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)
  33. .sp
  34. .VS
  35. char *
  36. \fBTcl_GetCommandName\fR(\fIinterp, token\fR)
  37. .VE
  38. .VE
  39. .SH ARGUMENTS
  40. .AS Tcl_CmdDeleteProc **deleteProcPtr
  41. .AP Tcl_Interp *interp in
  42. Interpreter in which to create new command.
  43. .AP char *cmdName in
  44. Name of command.
  45. .AP Tcl_CmdProc *proc in
  46. Implementation of new command:  \fIproc\fR will be called whenever
  47. \fIcmdName\fR is invoked as a command.
  48. .AP ClientData clientData in
  49. Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR.
  50. .AP Tcl_CmdDeleteProc *deleteProc in
  51. Procedure to call before \fIcmdName\fR is deleted from the interpreter;
  52. allows for command-specific cleanup.  If NULL, then no procedure is
  53. called before the command is deleted.
  54. .AP Tcl_CmdInfo *infoPtr in/out
  55. .VS
  56. Pointer to structure containing various information about a
  57. Tcl command.
  58. .AP Tcl_Command token in
  59. Token for command, returned by previous call to \fBTcl_CreateCommand\fR.
  60. The command must not have been deleted.
  61. .VE
  62. .BE
  63.  
  64. .SH DESCRIPTION
  65. .PP
  66. \fBTcl_CreateCommand\fR defines a new command in \fIinterp\fR and associates
  67. it with procedure \fIproc\fR such that whenever \fIcmdName\fR is
  68. invoked as a Tcl command (via a call to \fBTcl_Eval\fR) the Tcl interpreter
  69. will call \fIproc\fR
  70. to process the command.  If there is already a command \fIcmdName\fR
  71. associated with the interpreter, it is deleted.
  72. .VS
  73. \fBTcl_CreateCommand\fR returns a token that may be used to refer
  74. to the command in subsequent calls to \fBTcl_GetCommandName\fR.
  75. .VE
  76. \fIProc\fP should have arguments and result that match the type
  77. \fBTcl_CmdProc\fR:
  78. .nf
  79. .RS
  80. typedef int Tcl_CmdProc(
  81. .RS
  82. ClientData \fIclientData\fR,
  83. Tcl_Interp *\fIinterp\fR,
  84. int \fIargc\fR,
  85. char *\fIargv\fR[]);
  86. .RE
  87. .RE
  88. .fi
  89. When \fIproc\fR is invoked the \fIclientData\fP and \fIinterp\fR
  90. parameters will be copies of the \fIclientData\fP and \fIinterp\fR
  91. arguments given to \fBTcl_CreateCommand\fR.
  92. Typically, \fIclientData\fR points to an application-specific
  93. data structure that describes what to do when the command procedure
  94. is invoked.  \fIArgc\fR and \fIargv\fR describe the arguments to
  95. the command, \fIargc\fR giving the number of arguments (including
  96. the command name) and \fIargv\fR giving the values of the arguments
  97. as strings.  The \fIargv\fR array will contain \fIargc\fR+1 values;
  98. the first \fIargc\fR values point to the argument strings, and the
  99. last value is NULL.
  100. .PP
  101. \fIProc\fR must return an integer code that is either \fBTCL_OK\fR, \fBTCL_ERROR\fR,
  102. \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR.  See the Tcl overview man page
  103. for details on what these codes mean.  Most normal commands will only
  104. return \fBTCL_OK\fR or \fBTCL_ERROR\fR.  In addition, \fIproc\fR must set
  105. \fIinterp->result\fR to point to a string value;
  106. in the case of a \fBTCL_OK\fR return code this gives the result
  107. of the command, and in the case of \fBTCL_ERROR\fR it gives an error message.
  108. The \fBTcl_SetResult\fR procedure provides an easy interface for setting
  109. the return value;  for complete details on how the \fIinterp->result\fR
  110. field is managed, see the \fBTcl_Interp\fR man page.
  111. Before invoking a command procedure,
  112. \fBTcl_Eval\fR sets \fIinterp->result\fR to point to an empty string, so simple
  113. commands can return an empty result by doing nothing at all.
  114. .PP
  115. .VS
  116. The contents of the \fIargv\fR array belong to Tcl and are not
  117. guaranteed to persist once \fIproc\fR returns:  \fIproc\fR should
  118. not modify them, nor should it set \fIinterp->result\fR to point
  119. anywhere within the \fIargv\fR values.
  120. Call \fBTcl_SetResult\fR with status \fBTCL_VOLATILE\fR if you want
  121. to return something from the \fIargv\fR array.
  122. .VE
  123. .PP
  124. \fIDeleteProc\fR will be invoked when (if) \fIcmdName\fR is deleted.
  125. This can occur through a call to \fBTcl_DeleteCommand\fR or \fBTcl_DeleteInterp\fR,
  126. or by replacing \fIcmdName\fR in another call to \fBTcl_CreateCommand\fR.
  127. \fIDeleteProc\fR is invoked before the command is deleted, and gives the
  128. application an opportunity to release any structures associated
  129. with the command.  \fIDeleteProc\fR should have arguments and
  130. result that match the type \fBTcl_CmdDeleteProc\fR:
  131. .nf
  132. .RS
  133. .sp
  134. typedef void Tcl_CmdDeleteProc(ClientData \fIclientData\fR);
  135. .sp
  136. .RE
  137. .fi
  138. The \fIclientData\fR argument will be the same as the \fIclientData\fR
  139. argument passed to \fBTcl_CreateCommand\fR.
  140. .PP
  141. \fBTcl_DeleteCommand\fR deletes a command from a command interpreter.
  142. Once the call completes, attempts to invoke \fIcmdName\fR in
  143. \fIinterp\fR will result in errors.
  144. If \fIcmdName\fR isn't bound as a command in \fIinterp\fR then
  145. \fBTcl_DeleteCommand\fR does nothing and returns -1;  otherwise
  146. it returns 0.
  147. There are no restrictions on \fIcmdName\fR:  it may refer to
  148. a built-in command, an application-specific command, or a Tcl procedure.
  149. .PP
  150. .VS
  151. \fBTcl_GetCommandInfo\fR checks to see whether its \fIcmdName\fR argument
  152. exists as a command in \fIinterp\fR.  If not then it returns 0.
  153. Otherwise it places information about the command in the structure
  154. pointed to by \fIinfoPtr\fR and returns 1.
  155. Tcl_CmdInfo structures have fields named \fIproc\fR, \fIclientData\fR,
  156. and \fIdeleteProc\fR, which have the same meaning as the corresponding
  157. arguments to \fBTcl_CreateCommand\fR.
  158. There is also a field \fIdeleteData\fR, which is the ClientData value
  159. to pass to \fIdeleteProc\fR;  it is normally the same as
  160. \fIclientData\fR but may be set independently using the
  161. \fBTcl_SetCommandInfo\fR procedure.
  162. .PP
  163. \fBTcl_SetCommandInfo\fR is used to modify the procedures and
  164. ClientData values associated with a command.
  165. Its \fIcmdName\fR argument is the name of a command in \fIinterp\fR.
  166. If this command exists then \fBTcl_SetCommandInfo\fR returns 0.
  167. Otherwise, it copies the information from \fI*infoPtr\fR to
  168. Tcl's internal structure for the command and returns 1.
  169. Note that this procedure allows the ClientData for a command's
  170. deletion procedure to be given a different value than the ClientData
  171. for its command procedure.
  172. .PP
  173. \fBTcl_GetCommandName\fR provides a mechanism for tracking commands
  174. that have been renamed.  Given a token returned by \fBTcl_CreateCommand\fR
  175. when the command was created, \fBTcl_GetCommandName\fR returns the
  176. string name of the command.  If the command has been renamed since it
  177. was created, then \fBTcl_GetCommandName\fR returns the current name.
  178. The command corresponding to \fItoken\fR must not have been deleted.
  179. The string returned by \fBTcl_GetCommandName\fR is in dynamic memory
  180. owned by Tcl and is only guaranteed to retain its value as long as the
  181. command isn't deleted or renamed;  callers should copy the string if
  182. they need to keep it for a long time.
  183. .VE
  184.  
  185. .SH KEYWORDS
  186. bind, command, create, delete, interpreter
  187.